home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / graphic / stk100.zip / STK.DOC < prev    next >
Text File  |  1990-10-20  |  38KB  |  910 lines
  1. **********************************************************************
  2.                     This file is part of
  3.  
  4.          STK -- The sprite toolkit -- version 1.0
  5.  
  6.               Copyright (C) Jari Karjala 1990
  7.  
  8. The sprite toolkit (STK) is a FreeWare toolkit for creating high
  9. resolution sprite graphics with PCompatible hardware. This toolkit 
  10. is provided as is without any warranty or such thing. See the file
  11. COPYING and the end of this file for further information.
  12.  
  13. **********************************************************************
  14.  
  15.  
  16. STK -- The Sprite ToolKit -- version 1.0, Oct 20, 1990 
  17.  
  18.  
  19.  
  20. Intro
  21. =====
  22.  
  23. The Sprite Toolkit (STK) contains the following sets of functions,
  24. (each function has its set name in front of it):
  25.  
  26. SPR             lowlevel interface to the sprite functions
  27. SPR_HIT         lowlevel collision detection routines
  28. SPR_FIO         lowlevel sprite file IO
  29. SPR_ANIM        higher level interface to the sprite functions
  30. GR              text IO in the graphics mode and keyboard functions
  31. MOUSE           INT 33 interface to the mouse functions.
  32.  
  33. Note that there are two different interface levels to the sprite
  34. routines. 
  35.  
  36. The lowlevel functions provide support for simple sprites which
  37. can be put into the screen, hidden from the screen or deleted.
  38. Collisions between them can be detected. The sprite data can
  39. be read from a file, too.
  40.  
  41. The higher level interface supports animated sprites which are
  42. composed of simple sprites. These animated sprites can move
  43. automatically along some preset direction vector and act on
  44. different special cases, such as hitting the boundary or other
  45. sprite.
  46.  
  47. The GR functions provide a familiar set of basic text IO
  48. functions, like putch, put and printf, but these functions work
  49. in the graphics mode. There are also GR functions for direct
  50. reading of the keymap. These functions detect multiple
  51. simultaneus keypresses, as required by most arcade style games.
  52.  
  53. The MOUSE functions provide a very simple interface to the mouse
  54. driver. They are not much more that names to the INT 33 functions.
  55.  
  56.  
  57.  
  58.  
  59. Using the lowlevel sprite functions
  60. ===================================
  61.  
  62.  
  63. Initializing
  64. ------------
  65.  
  66. The first thing to do in a program which uses the STK is to
  67. start the graphics mode and initialize the sprites. This is done
  68. by the functions gr_detect, gr_start and spr_initialize (for
  69. further information, see The STK Function Reference). Now we are
  70. ready to use the STK functions.
  71.  
  72.  
  73. Creating and destroying sprites
  74. -------------------------------
  75.  
  76. The sprites are represented by SPRITE handles. The exact definition
  77. of the object pointed by a handle is private to the STK
  78. implementation, therefore the sprites can be manipulated only
  79. with the provided functions.
  80.  
  81. Each sprite has a shape defined by a sprite map. These can be
  82. created by the SPRED sprite editor. Each sprite map contains the
  83. actual shape of the sprite and the mask which describe the
  84. transparent parts of the sprite.
  85.  
  86. We must create sprites before we can do anything with them. This
  87. is done with the function spr_create, if we have the sprite
  88. shape bitmaps in static arrays, or with the function
  89. spr_fio_read_smp if the shape is in a sprite map file. Both of
  90. these functions return a SPRITE handle. You can make copies of
  91. sprites by the spr_copy function (you should spr_share the
  92. sprite first to save memory, since copies of shared sprites
  93. share the shape data which can take quite much memory).
  94.  
  95. The sprite resolution parameter in the spr_create means the
  96. number of shifted images per 8 pixels, ie 4 means that the X
  97. coordinates 0 and 1 will map into the same screen position.  Try
  98. giving a numeric parameter (1,2,4,8) to the StarMines program to
  99. see the effect of resolution parameter (for example "sm 4").
  100.  
  101. Each sprite should be though of as an object with its own
  102. identity and properties like the current location, the shape
  103. data and the identifier. If you need many sprites with the same
  104. shape, you should use the spr_copy to make copies, NOT to try to
  105. display the same sprite many times at different locations.
  106.  
  107. When the sprite is no longer needed it should be destroyed with
  108. the spr_delete function, which releases all the resources used
  109. by the sprite.
  110.  
  111.  
  112. How much memory do we need
  113. --------------------------
  114.  
  115. A sprite which is W bytes wide and H scanlines tall and uses
  116. sprite resolution S takes 2*S*((W+1)*H) + 2*(W+1)*H bytes of
  117. memory from far heap and only about 40 bytes from the near heap.
  118. This means that the small memory model is big enough in most
  119. applications. 
  120.  
  121. Example: the sprite is 32 pixels (4 bytes) wide, 24 pixels tall
  122. and we want the best resolution (8). The sprite will need
  123. 2*8*((4+1)*24) + 2*(4+1)*24 = 2160 bytes memory. 
  124.  
  125. The memory consumption is one of the reasons why my sprites are
  126. monochrome, they would need 4 times as much memory (in the
  127. example over 8 kbytes for one sprite!) if they had 16 colors.
  128. Also the output would be four times slower making it impossible
  129. to use one pixel resolution in movements with anything slower
  130. than 16 MHz.
  131.  
  132. If sharing is used then the N copies will take 2*S*((W+1)*H) +
  133. 2*(W+1)*H*N bytes of memory from the far heap plus those 40
  134. bytes of near heap for each copy.
  135.  
  136.  
  137. Manipulating sprites
  138. --------------------
  139.  
  140. A sprite can be put into the screen with the function spr_put.
  141. A sprite which has been put into the screen can be hidden by the
  142. function spr_hide.  Displaying and hiding sprites do not take
  143. place immediately, but only after the next call to the function
  144. spr_next_pass. This function should be called in the main loop
  145. of the program after all sprites have been spr_put into their
  146. current positions.
  147.  
  148. What the spr_next_pass really does? It draws all the sprites
  149. which have been spr_put after the previous spr_next_pass into
  150. the hidden display page (and saves the background below them).
  151. Then that display page is activated and the sprites which are in
  152. the now-hidden page are deleted by restoring the previously
  153. saved background data. Therefore you must spr_put the sprites
  154. during every pass of the main loop of the program.
  155.  
  156. The method described above makes it possible to achieve
  157. reasonably fast flicker-free animation. There is a problem with
  158. this approach: EGA graphics cards are slow changing video pages,
  159. and therefore we must waste about 10 milliseconds waiting after
  160. the screen flip. Hercules cards do not need this wait-state,
  161. therefore Hercules mode is preferred in slower machines. Note
  162. that this wait-state affects the frame speed, and it should be
  163. regulated with the spr_regulate_speed function.
  164.  
  165. The collision detection should be done after all the sprites
  166. have been spr_put but before the spr_next_pass. It is possible
  167. to either check the collision between a sprite and a coordinate
  168. position, the collision between two sprites (spr_hit) or find
  169. all the sprites a given sprite collides (spr_hit_first and
  170. spr_hit_next). All collisions are first checked by the bounding
  171. box and after that by using the mask map of the sprite.
  172.  
  173. You can retrieve information about a given sprite by the
  174. functions spr_get_id, spr_get_x, spr_get_y, spr_get_width and
  175. spr_get_height.
  176.  
  177.  
  178.  
  179.  
  180. Using the higher level sprite functions
  181. =======================================
  182.  
  183.  
  184. Creating and destroying animated sprites
  185. ----------------------------------------
  186.  
  187. The animated sprites are represented by ANIM_SPRITE handles. The
  188. exact definition of the object pointed by a handle is private to
  189. the STK implementation, therefore the sprites can be manipulated
  190. only with the provided functions.
  191.  
  192. The ANIM_SPRITEs are created by the function spr_anim_create.
  193. This function takes simple sprites as parameters. These should
  194. have been generated earlier, for example by the function
  195. spr_create. Note that you must have different instances of
  196. simple sprites for each animated sprite you create. 
  197.  
  198. An animated sprite is deleted by the function spr_anim_delete.
  199. This function will not delete the simple sprites it contains. If
  200. also the simple sprites need to be deleted the function
  201. spr_anim_destroy must be use